Ereignisse

Admin Power Pack tauscht Ereignisse („FpEvents") mit anderen Fluxpunkt-Modulen aus: Es empfängt Steuerereignisse, die dieselben Wartungs- und Systemaktionen auslösen wie die XML-RPC-Befehle und die HTTP-API, und sendet je Wartungsaktion ein Abschlussereignis mit dem Ergebnis — nur die Systemaktionen Neustart und Update senden keines. Typische Konsumenten sind EventBridge (Weiterleitung als Webhook, E-Mail, Syslog oder Datenbankeintrag) und eigene STARFACE-Module, die Ereignisse direkt abonnieren oder senden. Seit Modulversion 26.8.19 sendet Admin Power Pack zusätzlich das Audit-Ereignis McpToolCalledEvent für jeden Aufruf des MCP-Servers.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen

Typ: FpEvents — der modulübergreifende Ereignismechanismus der Fluxpunkt-Module auf dem anlageninternen Ereignisbus. Es handelt sich um keine Netzwerkschnittstelle: Ereignisse sind nur innerhalb der Anlage erreichbar; nach außen gelangen sie über EventBridge.
Identifikator: der Ereignisname, z. B. ExecuteDeleteLogs oder LogsDeletedEvent. Die Namen sind anlagenweit gültig und unabhängig vom Namen der Modulkonfiguration.
Nutzlast: ein JSON-Objekt. Felder ohne Wert (null) entfallen in der Nutzlast; unbekannte Felder werden beim Empfang ignoriert.
Zugriff: EventBridge abonniert Ereignisse per Konfiguration und kann Steuerereignisse als Aktion senden. Eigene Module verwenden die Modulfunktionen FpEvent abonnieren / FpEvent senden — Download und Anleitung im Artikel Schnittstellen & APIs. Zusätzlich sendet Admin Power Pack die Wartungs-Steuerereignisse selbst zeitgesteuert über die Geplanten Aktionen im Tab STARFACE Verwaltung; die Systemaktions-Ereignisse planen stattdessen über ihr Feld executeAt.
Lizenz: Die Ausführung empfangener Steuerereignisse ist lizenzgebunden — ohne gültige Modullizenz werden sie verworfen (Eintrag im Modul-Log).
Verfügbar seit: Wartungsereignisse Modulversion 26.6.12, Benutzervorlagen-Ereignisse Modulversion 26.5.8; die Systemaktions-Ereignisse ExecuteStarfaceRestart und ExecuteStarfaceUpdate sowie das MCP-Audit-Ereignis McpToolCalledEvent seit Modulversion 26.8.19

Gemeinsame Felder

Alle Wartungsereignisse — Steuer- wie Abschlussereignisse — tragen zwei gemeinsame Felder:

Feld	Typ	Beschreibung
`trigger`	String	Herkunft der Ausführung: `EVENT` (anderes Modul/Ereignis), `TIMER` (Geplante Aktion), `MANUAL` (Schaltfläche in der Moduloberfläche), `API` (XML-RPC- oder HTTP-API-Aufruf). In Steuerereignissen optional; fehlt der Wert oder ist er unbekannt, gilt `EVENT`. Das Abschlussereignis übernimmt den Wert des auslösenden Steuerereignisses.
`timerName`	String, optional	Name der Geplanten Aktion, die den Befehl ausgelöst hat; nur bei `trigger` = `TIMER` gesetzt, sonst nicht enthalten.

Empfangene Steuerereignisse

Jedes Steuerereignis löst genau eine Wartungsaktion aus. Die Felder und ihre Bedeutung entsprechen den Parametern des jeweiligen XML-RPC-Befehls — zuzüglich der gemeinsamen Felder.

Ereignis	Wirkung	Felder (zusätzlich zu `trigger`, `timerName`)
`ExecuteAutoCleanup`	Auto-Cleanup ausführen	–
`ExecuteDeleteSystemMessages`	Systemmeldungen löschen	–
`ExecuteDeleteLogs`	Logdateien löschen	`scope`: `old` \| `all` (Standard `old`)
`ExecuteDeleteTemporaryFiles`	Temporäre Dateien löschen	–
`ExecuteDeleteRecordings`	Gesprächsaufzeichnungen löschen	–
`ExecuteDeleteFaxes`	Faxe löschen	–
`ExecuteDeleteCallData`	Ruflisteneinträge löschen	`startTime`, `endTime` (Zeitstempel in ms), `incoming`, `outgoing`, `missed`, `answered` (Boolean, Standard `true`), `filter` (String), `confirmed` (Boolean, muss `true` sein)
`ExecuteDeleteFirmware`	Firmware-Dateien löschen	`vendor`: `all` \| `snom` \| `yealink` \| `gigaset` \| `other` (Standard `all`)
`ExecuteDeleteBackups`	Sicherungen löschen	`scope`: `all` \| `allExceptLast` (Standard `allExceptLast`)
`ExecuteReRegisterTrunks`	Leitungen neu anmelden	–
`ExecuteHangupAllCalls`	Alle Gespräche beenden	–
`ExecuteProvisionDevices`	Endgeräte provisionieren	`type`: `check-sync` \| `check-sync-reboot` \| `reboot-snom` \| `factory-reset-snom` \| `factory-reset-yealink` (Pflicht)

Beispiel-Nutzlasten — ein parameterloses Steuerereignis und zwei mit Parametern:

ExecuteAutoCleanup
{
  "trigger": "TIMER"
}

ExecuteDeleteLogs
{
  "scope": "old",
  "trigger": "TIMER"
}

ExecuteDeleteCallData
{
  "startTime": 0,
  "endTime": 1767225600000,
  "incoming": true,
  "outgoing": true,
  "missed": true,
  "answered": true,
  "filter": "+4972112345678",
  "confirmed": true,
  "trigger": "EVENT"
}

ExecuteDeleteCallData ohne confirmed = true und ExecuteProvisionDevices ohne type werden still verworfen.

`ExecuteUserTemplate` — Benutzervorlage anwenden

Zusätzlich zu den Wartungsbefehlen empfängt Admin Power Pack ein Steuerereignis, das eine Benutzervorlage aus dem Tab Benutzer & Gruppen auf STARFACE-Benutzer anwendet. Gruppen in accountIds werden transitiv zu ihren Mitgliedern aufgelöst.

Feld	Typ	Pflicht	Beschreibung
`templateId`	String	ja	ID der Benutzervorlage. Ereignisse mit unbekannter ID werden verworfen.
`accountIds`	Array von Integer	ja	Account-IDs der Zielbenutzer oder -gruppen; leere Listen werden verworfen.
`includeAdmins`	Boolean	nein	Auch Benutzer mit Administrationsrecht einbeziehen (Standard `false`).

ExecuteUserTemplate
{
  "templateId": "3f2b7c9e-5d41-4c8a-9b1f-2a6d8e4f7c10",
  "accountIds": [12, 17, 23],
  "includeAdmins": false
}

Systemaktionen

Verfügbar seit Modulversion 26.8.19

Die beiden Systemaktions-Ereignisse sind seit Modulversion 26.8.19 enthalten; ältere Modulversionen ignorieren sie.

Admin Power Pack empfängt zwei Steuerereignisse für die Systemaktionen der Karte Setup & Recovery: STARFACE-Neustart und STARFACE-Update — sofort oder einmalig zu einem geplanten Zeitpunkt (executeAt). Eine zukünftige Planung wird gespeichert, überdauert Modul-Neustarts und wird durch ein neues Ereignis ersetzt; die Moduloberfläche zeigt sie an und kann sie abbrechen. Verstreicht ein geplanter Zeitpunkt, während Modul oder Anlage nicht laufen, holt das Modul die Aktion kurz nach dem nächsten Modulstart nach (etwa 30 Sekunden Verzögerung).

Ereignis	Wirkung	Felder (zusätzlich zu `trigger`, `timerName`)
`ExecuteStarfaceRestart`	STARFACE neu starten — entspricht `RestartStarface`	`mode`: `service` (nur STARFACE-Dienste, Standard) \| `server` (kompletter Server); `executeAt`: ISO-8601-Zeitpunkt (`JJJJ-MM-TTThh:mm`, Anlagenzeit) — leer/vergangen = sofort, zukünftig = einmalig geplant
`ExecuteStarfaceUpdate`	STARFACE-Update ausführen — entspricht `UpdateStarface`	`version`: verfügbare Zielversion; `latest` oder leer = neueste angebotene Version (inkl. Beta, falls in der Anlage aktiviert); `executeAt`: wie bei `ExecuteStarfaceRestart`

Beide Aktionen senden kein Abschlussereignis — Neustart bzw. Update beenden die STARFACE-Dienste, eine Bestätigung ist danach nicht mehr möglich. trigger und timerName dürfen mitgesendet werden, bleiben ohne Abschlussereignis aber ohne sichtbare Wirkung. ExecuteStarfaceRestart mit ungültigem mode und ExecuteStarfaceUpdate mit nicht verfügbarer Zielversion werden still verworfen (Log-Eintrag).

ExecuteStarfaceRestart
{
  "mode": "service",
  "executeAt": "2026-08-12T22:00",
  "trigger": "EVENT"
}

ExecuteStarfaceUpdate
{
  "version": "latest",
  "executeAt": "2026-08-12T22:00",
  "trigger": "EVENT"
}

Gesendete Abschlussereignisse

Nach jeder ausgeführten Wartungsaktion veröffentlicht Admin Power Pack genau ein Abschlussereignis. Es bestätigt die tatsächliche Ausführung — im Gegensatz zur XML-RPC-Antwort, die nur die Annahme meldet — und übernimmt trigger und timerName des Auslösers. Die Systemaktionen Neustart und Update senden kein Abschlussereignis.

Ereignis	Folgt auf	Felder (zusätzlich zu `trigger`, `timerName`)
`AutoCleanupExecutedEvent`	`ExecuteAutoCleanup`	–
`SystemMessagesDeletedEvent`	`ExecuteDeleteSystemMessages`	–
`LogsDeletedEvent`	`ExecuteDeleteLogs`	`scope` — der wirksame Umfang (`old`/`all`)
`TemporaryFilesDeletedEvent`	`ExecuteDeleteTemporaryFiles`	–
`RecordingsDeletedEvent`	`ExecuteDeleteRecordings`	–
`FaxesDeletedEvent`	`ExecuteDeleteFaxes`	–
`CallDataDeletedEvent`	`ExecuteDeleteCallData`	`deletedSummary` (Integer) — gelöschte Ruflisteneinträge; `deletedData` (Integer) — gelöschte Detailzeilen; `message` (String) — Ergebnistext
`FirmwareDeletedEvent`	`ExecuteDeleteFirmware`	`vendor` — der wirksame Hersteller
`BackupsDeletedEvent`	`ExecuteDeleteBackups`	`scope` — der wirksame Umfang (`all`/`allExceptLast`)
`TrunksReRegisteredEvent`	`ExecuteReRegisterTrunks`	–
`AllCallsHungUpEvent`	`ExecuteHangupAllCalls`	–
`DevicesProvisionedEvent`	`ExecuteProvisionDevices`	`type` — der gesendete Provisionierungstyp

message in CallDataDeletedEvent nimmt einen der folgenden Werte an: „Alle Ruflisteneinträge wurden gelöscht." (vollständige Löschung), „Ruflisteneinträge wurden gelöscht." (Zeit-/Kategorienfilter), „Gefilterte Ruflisteneinträge wurden gelöscht." (Rufnummern-/Namensfilter) oder „Fehler beim Löschen." (Abbruch, Zähler dann 0).

Beispiel-Nutzlasten:

AutoCleanupExecutedEvent — ausgelöst durch eine Geplante Aktion
{
  "trigger": "TIMER",
  "timerName": "Nächtliche Bereinigung"
}

LogsDeletedEvent — ausgelöst per XML-RPC
{
  "scope": "old",
  "trigger": "API"
}

CallDataDeletedEvent
{
  "deletedSummary": 1284,
  "deletedData": 5210,
  "message": "Ruflisteneinträge wurden gelöscht.",
  "trigger": "API"
}

DevicesProvisionedEvent
{
  "type": "check-sync-reboot",
  "trigger": "API"
}

Anwendungsbeispiel

Sie stoßen abends per XML-RPC eine Provisionierung mit check-sync-reboot an. EventBridge abonniert DevicesProvisionedEvent und meldet den Abschluss als Nachricht in Ihren Teams-Kanal — Ihr Deployment-Skript muss nicht pollen, und das Protokoll zeigt, ob der Rollout zeitgesteuert oder per API lief.

`UserTemplateExecutedEvent` — Benutzervorlage angewendet

Wird nach jeder Anwendung einer Benutzervorlage veröffentlicht — gleich, ob sie manuell in der Oberfläche, über einen Vorlagen-Timer oder per ExecuteUserTemplate ausgelöst wurde. Bei Timer-Ausführung erscheint das Ereignis je angewendeter Vorlage mehrfach (einmal je Zielbenutzer), jeweils mit der vollständigen Kontenliste.

Feld	Typ	Beschreibung
`templateId`	String	ID der angewendeten Benutzervorlage.
`templateName`	String	Name der Benutzervorlage.
`accountIds`	Array von Integer	Account-IDs der Zielbenutzer (Gruppen bereits aufgelöst).
`includeAdmins`	Boolean	Ob Administratoren einbezogen wurden.
`trigger`	String	`MANUAL` (Oberfläche), `TIMER` (Vorlagen-Timer) oder `EVENT` (`ExecuteUserTemplate`). Der Wert `API` kommt hier nicht vor.
`timerName`	String, optional	Name des Vorlagen-Timers; nur bei `trigger` = `TIMER`.

UserTemplateExecutedEvent
{
  "templateId": "3f2b7c9e-5d41-4c8a-9b1f-2a6d8e4f7c10",
  "templateName": "Standard-Benutzer",
  "accountIds": [12, 17, 23],
  "includeAdmins": false,
  "trigger": "TIMER",
  "timerName": "Nächtlicher Abgleich"
}

MCP-Audit-Ereignis (McpToolCalledEvent)

Der MCP-Server veröffentlicht für jede Anfrage, die seinen Endpunkt erreicht, ein McpToolCalledEvent — für erfolgreiche Werkzeugaufrufe ebenso wie für abgewiesene. Das Modul führt bewusst keine eigene Audit-Tabelle: Wer den MCP-Zugriff protokollieren will, abonniert dieses Ereignis (typisch: Weiterleitung an Syslog über EventBridge). Die Argumente des Werkzeugaufrufs sind nicht enthalten — sie können Klartext-Kundendaten tragen; was der Aufruf berührt hat, fasst target zusammen.

Feld	Typ	Beschreibung
`timestamp`	Integer	Zeitpunkt der Beantwortung (Millisekunden-Zeitstempel).
`tokenLabel`	String	Bezeichnung des authentifizierenden API-Tokens — nie der Token selbst. Entfällt, wenn die Anfrage vor der Token-Prüfung abgewiesen wurde.
`remoteAddr`	String	Quelladresse — bei vertrauenswürdigem Proxy die aufgelöste Client-Adresse.
`tool`	String	Werkzeugname, z. B. `status_overview`. Entfällt, wenn die Anfrage vor der Werkzeugauflösung abgewiesen wurde.
`operation`	String	Operation innerhalb des Werkzeugs, z. B. `get`. Entfällt, wenn nicht aufgelöst.
`mode`	String	Wirksamer Modus des Werkzeugs zum Aufrufzeitpunkt: `READ` oder `READ_WRITE`.
`destructive`	Boolean	Ob die Operation als destruktiv eingestuft ist.
`confirmed`	Boolean	Ob der Aufrufer `confirm: true` übergeben hat.
`durationMs`	Integer	Dauer des Aufrufs in Millisekunden.
`resultChars`	Integer	Größe des serialisierten Ergebnisses in Zeichen; `0` bei abgewiesenen Aufrufen.
`outcome`	String	Ausgang: `OK`, `TOOL_ERROR` (fachlicher Fehler), `DENIED_IP`, `DENIED_TOKEN`, `DENIED_LICENSE`, `DENIED_TOOL_DISABLED` (Server aus oder Werkzeug nicht freigegeben), `DENIED_READ_ONLY`, `DENIED_UNCONFIRMED` (destruktiv ohne `confirm: true`) oder `FAILED` (interner Fehler).
`target`	String, optional	Kurze, unkritische Zusammenfassung dessen, was der Aufruf berührt hat.
`error`	String, optional	Fehlertext bei fehlgeschlagenen Aufrufen.

McpToolCalledEvent — erfolgreicher Leseaufruf
{
  "timestamp": 1755640800000,
  "tokenLabel": "Claude Code (F. Wolf)",
  "remoteAddr": "192.168.10.42",
  "tool": "status_trunks",
  "operation": "lines",
  "mode": "READ",
  "destructive": false,
  "confirmed": false,
  "durationMs": 184,
  "resultChars": 2311,
  "outcome": "OK"
}

McpToolCalledEvent — abgewiesener Aufruf (Token ungültig)
{
  "timestamp": 1755640860000,
  "remoteAddr": "203.0.113.7",
  "destructive": false,
  "confirmed": false,
  "durationMs": 0,
  "resultChars": 0,
  "outcome": "DENIED_TOKEN"
}

Die DENIED_…-Einträge sind gerade die, die in ein Syslog gehören: Sie zeigen abgewiesene Zugriffsversuche mit Quelladresse und Grund.

Fehlerbehandlung

Der Ereignisweg arbeitet nach dem Fire-and-forget-Prinzip: Es gibt keine Fehlerereignisse und keine Empfangsbestätigung. Ein Steuerereignis, das nicht ausgeführt wird, bleibt ohne Abschlussereignis; die Ursache steht im Modul-Log:

Situation	Verhalten
Keine gültige Modullizenz	Steuerereignis wird verworfen (Log-Eintrag).
`ExecuteDeleteCallData` ohne `confirmed` = `true`	Verworfen — die Löschung ist unwiderruflich und verlangt die ausdrückliche Bestätigung.
`ExecuteProvisionDevices` ohne `type`	Verworfen.
`ExecuteUserTemplate` mit unbekannter `templateId` oder leerer Kontenliste	Verworfen.
`ExecuteStarfaceRestart` mit ungültigem `mode`	Verworfen (Log-Eintrag).
`ExecuteStarfaceUpdate` mit nicht verfügbarer Zielversion oder ohne verfügbares Update	Verworfen (Log-Eintrag).
Unbekannte Felder in der Nutzlast	Werden ignoriert; das Ereignis wird normal verarbeitet.
Unbekannter Wert in `trigger`	Wird wie `EVENT` behandelt.

Ausbleibende Abschlussereignisse sind damit das Signal, im Modul-Log nachzusehen — außer bei den Systemaktionen Neustart und Update, die grundsätzlich keines senden.

Versionierung & Kompatibilität

Ereignisnamen und Feldnamen sind stabile Verträge; Erweiterungen erfolgen additiv (neue Ereignisse, neue optionale Felder). Verarbeiten Sie Nutzlasten daher tolerant gegenüber zusätzlichen Feldern. Den anlagenweiten Ereigniskatalog mit Beispiel-Nutzlasten führt die Ereignisliste der EventBridge-Dokumentation; Änderungen an den Ereignissen dokumentieren die Release Notes der jeweiligen Modulversion.

Grundlagen​

Gemeinsame Felder​

Empfangene Steuerereignisse​

ExecuteUserTemplate — Benutzervorlage anwenden​

Systemaktionen​

Gesendete Abschlussereignisse​

UserTemplateExecutedEvent — Benutzervorlage angewendet​

MCP-Audit-Ereignis (McpToolCalledEvent)​

Fehlerbehandlung​

Versionierung & Kompatibilität​